b/519408868

This PR introduces the migrations-functional-testing agent skill under .agent/skills/. This skill equips the AI agent with a modular, gated workflow to perform end-to-end functional testing of Dataflow templates against local code changes using GCP resources.

IMPORTANT: The skill clearly mentions that it is to be used ONLY for migrations specific pipelines i.e. sourcedb-to-spanner, spanner-to-sourcedb, datastream-to-spanner and gcs-spanner-dv as it's written only keeping these in mind.

Key Features

1. Topology & Schema Planning: Analyzes repository code changes, maps source/sink configurations, and plans test cases.
2. Autonomous Provisioning: Autonomously provisions ephemeral Spanner and Cloud SQL instances once the proposed plans are approved.
3. Database Credential Management: Safely requests database user credentials or offers to autonomously generate a temporary DB user and password for Cloud SQL.
4. Optimized Staging: Stage jobs using standard public Dataflow template paths or packages local modifications using optimized Maven flags (skipping Spotless, Checkstyle, and unit tests to minimize latency).
5. Custom & Sharding Transformations: Detects if a custom/sharding JAR is required, plans the transformation logic, builds the JAR, uploads it to GCS, and wires the paths into the Terraform configurations.
6. Strict Safety & Approval Gates: Enforces "Stop and Wait" gates for code analysis, schema setups, configuration files, and Terraform variables. Once approved, the agent executes tasks (like running Terraform apply) autonomously.
7. Verification & Success Criteria: Proposes destination table verification queries, explicit DLQ checks (dlq/ and filteredEvents/ GCS folders), and generates a final markdown verification report.

Files Added/Modified

• [NEW] SKILL.md: The core instruction set defining the orchestrator workflow, safety gates, and automation rules.
• [NEW] TEST.md: A step-by-step manual test case designed for reviewers to verify the skill using a custom transformation scenario.
• [NEW] skills_index.md: Added the index references to map to the new skill directory and name.

Verification Run

2 tests were done:

1. Testing Custom transformation in sourcedb-to-spanner without any new changes
2. Testing a new feature to support custom transformations in gcs-spanner-dv (Github PR)

Analysis:

• Since a lot of these changes are gated with user approval, it is a bit hands on but that's by design.
• It does improve the functional testing experience by a lot as most things are done autonomously by agent and requires user attention mainly at the beginning (during curation of test cases and setup).
• The test cases do require some attention and customization from user - this is super important.
• The setup creation is quite good as per the pre-decided test cases and requires minimal prompting from user and the agent is able to clearly define the success criteria, etc.
• Sometimes the agent might prompt the user to do some steps (example create the custom transformation jar) but the agent is able to do it by itself once prompted from user - there were some improvements made to better this experience
• The agent was able to successfully utilise the debugging skill to track job progress, debug issues, make changes and re-run the job. The follow up jobs were a success.
• The agent tracks job progress and autonomously queries destination and prepares test success report clearly stating successes and failures after test execution.

Follow up work

The test cases do require some attention and customization from user. There will be a follow-up effort to add a skill to improve creating edge cases which will be referred to here once its completed.